Skip to main content
Expert Talk
Amakomaya — Aamako Maya Apps Pvt. Ltd.

Architecture Decision Records

An Architecture Decision Record is a short document capturing one decision: the context, the options considered, what was chosen, and what it costs. One decision, one file, numbered, never deleted.

The practice matters more in public health than in most sectors. Ministry and programme staff rotate; consultants leave when the contract ends; the system outlives everyone who designed it. Five years later someone asks why does the national ID appear in three different formats? and the honest answer — "the person who decided that left in 2021" — is expensive.

Why not just a design document​

A design document describes the current design. It gets edited, and the edits erase the reasoning. An ADR log is append-only: it records that in March you chose deterministic-only patient matching because the demographic data quality did not support probabilistic scoring, which tells the person in 2027 exactly what to re-examine when data quality improves.

Superseding an ADR is normal. Deleting one is not.

The format​

Kept deliberately short — one to two pages. Longer ADRs do not get written.

# ADR-0014: Use deterministic matching for the national client registry

- **Status:** Accepted
- **Date:** 2026-03-11
- **Deciders:** Architecture review board
- **Supersedes:** —
- **Superseded by:** —

## Context
What is true that forces a decision now. Constraints, data, deadlines.

## Options considered
Each option with its consequences — not a straw man.

## Decision
What was chosen, stated in one sentence, in the active voice.

## Consequences
What becomes easier, what becomes harder, what is now committed to.

## Implications
- **Security and privacy:**
- **Interoperability:**
- **Scalability and operations:**
- **Cost:**
- **Clinical safety:**

The Implications block is the health-specific addition. Every architecture decision in this sector has a clinical safety dimension, and forcing a line for it catches the decisions that would otherwise be made purely on cost.

Statuses: Proposed → Accepted → Superseded (or Rejected, Deprecated).

A ready-to-copy version is in templates/architecture-decision-record.

Decisions worth an ADR in a health architecture​

If you write only ten ADRs, write these:

  1. The patient identifier — which identifier is authoritative, what happens when it is absent, and who may issue a temporary one
  2. The matching strategy — deterministic, probabilistic or hybrid; who adjudicates possible matches; see MPI
  3. The exchange pattern — centralised, federated or hybrid; see HIE patterns
  4. The exchange standard and version — e.g. FHIR R4 with named profiles, and the upgrade policy
  5. Terminology bindings — which code systems are required, preferred or example-only, and who maintains the value sets
  6. The authorisation model — RBAC, ABAC, or SMART scopes; see OAuth and OIDC
  7. The consent model — opt-in, opt-out, or purpose-based; what break-glass means and how it is audited
  8. Data residency and hosting — in-country, cloud region, or hybrid, and the legal basis
  9. The offline strategy — what works without connectivity and how conflicts resolve; see offline-first
  10. What the analytics layer consumes — copies of clinical data, aggregates, or a query federation

Worked example​

ADR-0007: Route all point-of-service traffic through the interoperability layer​

Status: Accepted · Date: 2026-01-20

Context. Four systems currently exchange data point-to-point (EMR↔lab, EMR↔HMIS, CHW app↔EMR, LMIS↔HMIS). Two more systems are procured for this year. Point-to-point growth is quadratic; each link re-implements authentication and has its own failure behaviour. No central audit trail exists, which we are required to produce for the data protection authority.

Options considered.

  1. Continue point-to-point. Cheapest per link, no new component to operate. Six systems implies up to fifteen links; no shared audit; each vendor negotiates credentials separately.
  2. Interoperability layer (OpenHIM or equivalent). Each system integrates once. Central audit and routing. Adds a component that must be operated at high availability and becomes a single point of failure if it is not.
  3. Direct FHIR server as hub. Simpler stack, but conflates storage with mediation and offers no transformation for the two HL7 v2 systems.

Decision. All inter-system traffic is routed through an interoperability layer. Direct point-to-point links are permitted only for existing integrations, and must be migrated before their next contract renewal.

Consequences. New systems integrate against one documented interface. Audit becomes a platform capability rather than a per-vendor promise. We now own an availability-critical component and must staff it — see ADR-0011 on the operating model.

Implications. Security: single point for authentication and audit; also a single high-value target, so it needs its own threat model. Interoperability: enables staged adoption of FHIR without rewriting the HL7 v2 systems. Scalability: must be sized for peak lab-result volume; queueing required. Cost: one additional environment plus 0.5 FTE operations. Clinical safety: an outage now blocks all exchange — degraded modes and store-and-forward are mandatory, not optional.

Keeping the log usable​

  • Number sequentially and never renumber. ADR-0007 is a citable address.
  • Store beside the code or the architecture repository, in version control, in the same pull request as the change where possible.
  • Index them. A table of number, title, status and date at the top of the directory.
  • Link ADRs from the design documents they explain, and from C4 diagrams.
  • Review superseded ADRs on a cycle. A decision made under a constraint that no longer holds is a candidate for revisiting — that is the whole point of recording the constraint.

References​

Last updated on